home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995 August: Tool Chest / Dev.CD Aug 95 TC / Dev.CD Aug 95 TC.toast / New System Software Extensions / QuickDraw™ 3D 1.0 / Development / Interfaces / QD3DCamera.h < prev    next >
Encoding:
C/C++ Source or Header  |  1995-06-02  |  9.7 KB  |  336 lines  |  [TEXT/MPS ]
  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DCamera.h                                             **
  4.  **                                                                          **
  5.  **                                                                          **
  6.  **     Purpose:     Generic camera routines                                      **
  7.  **                                                                          **
  8.  **                                                                          **
  9.  **                                                                          **
  10.  **     Copyright (C) 1991-1995 Apple Computer, Inc. All rights reserved.     **    
  11.  **                                                                          **
  12.  **                                                                          **
  13.  *****************************************************************************/
  14. #ifndef QD3DCamera_h
  15. #define QD3DCamera_h
  16.  
  17. #ifndef QD3D_h
  18. #include "QD3D.h"
  19. #endif  /*  QD3D_h  */
  20.  
  21. #if PRAGMA_ONCE
  22.     #pragma once
  23. #endif
  24.  
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif    /* __cplusplus */
  28.  
  29.  
  30. /******************************************************************************
  31.  **                                                                             **
  32.  **                            Data Structure Definitions                         **
  33.  **                                                                             **
  34.  *****************************************************************************/
  35. /*
  36.  *  The placement of the camera.
  37.  */
  38. typedef struct TQ3CameraPlacement{
  39.     TQ3Point3D        cameraLocation;        /*  Location point of the camera     */
  40.     TQ3Point3D        pointOfInterest;    /*  Point of interest                 */
  41.     TQ3Vector3D        upVector;            /*  "up" vector                     */
  42. } TQ3CameraPlacement;
  43.  
  44.  
  45. /*
  46.  *  The range of the camera.
  47.  */
  48. typedef struct TQ3CameraRange {
  49.     float    hither;        /*  Hither plane, measured from "from" towards "to"    */
  50.     float    yon;        /*  Yon  plane, measured from "from" towards "to"     */
  51. } TQ3CameraRange;
  52.  
  53.  
  54. /*
  55.  *  Viewport specification.  Origin is (-1, 1), and corresponds to the 
  56.  *  upper left-hand corner; width and height maximum is (2.0, 2.0),
  57.  *  corresponding to the lower left-hand corner of the window.  The
  58.  *  TQ3Viewport specifies a part of the viewPlane that gets displayed 
  59.  *    on the window that is to be drawn.
  60.  *  Normally, it is set with an origin of (-1.0, 1.0), and a width and
  61.  *  height of both 2.0, specifying that the entire window is to be
  62.  *  drawn.  If, for example, an exposure event of the window exposed
  63.  *  the right half of the window, you would set the origin to (0, 1),
  64.  *  and the width and height to (1.0) and (2.0), respectively.
  65.  *
  66.  */
  67. typedef struct TQ3CameraViewPort {
  68.     TQ3Point2D        origin;
  69.     float            width;
  70.     float            height;
  71. } TQ3CameraViewPort;
  72.  
  73.  
  74. typedef struct TQ3CameraData {
  75.     TQ3CameraPlacement    placement;
  76.     TQ3CameraRange        range;
  77.     TQ3CameraViewPort    viewPort;
  78. } TQ3CameraData;
  79.  
  80.  
  81. /*
  82.  *  An orthographic camera.
  83.  *
  84.  *  The lens characteristics are set with the dimensions of a
  85.  *  rectangular viewPort in the frame of the camera.
  86.  */
  87. typedef struct TQ3OrthographicCameraData {
  88.     TQ3CameraData        cameraData;
  89.     float                left;
  90.     float                top;
  91.     float                right;
  92.     float                bottom;
  93. } TQ3OrthographicCameraData;
  94.  
  95. /*
  96.  *  A perspective camera specified in terms of an arbitrary view plane.
  97.  *
  98.  *  This is most useful when setting the camera to look at a particular
  99.  *  object.  The viewPlane is set to distance from the camera to the object.
  100.  *  The halfWidth is set to half the width of the cross section of the object,
  101.  *  and the halfHeight equal to the halfWidth divided by the aspect ratio
  102.  *  of the viewPort.
  103.  * 
  104.  *  This is the only perspective camera with specifications for off-axis
  105.  *  viewing, which is desirable for scrolling.
  106.  */
  107. typedef struct TQ3ViewPlaneCameraData {
  108.     TQ3CameraData        cameraData;
  109.     float                viewPlane;
  110.     float                halfWidthAtViewPlane;
  111.     float                halfHeightAtViewPlane;
  112.     float                centerXOnViewPlane;
  113.     float                centerYOnViewPlane;
  114. } TQ3ViewPlaneCameraData;
  115.  
  116. /*
  117.  *    A view angle aspect camera is a perspective camera specified in 
  118.  *    terms of the minimum view angle and the aspect ratio of X to Y.
  119.  *
  120.  */
  121. typedef struct TQ3ViewAngleAspectCameraData {
  122.     TQ3CameraData        cameraData;
  123.     float                fov;
  124.     float                aspectRatioXToY;
  125. } TQ3ViewAngleAspectCameraData;
  126.  
  127.  
  128. /******************************************************************************
  129.  **                                                                             **
  130.  **                            Generic Camera routines                             **
  131.  **                                                                             **
  132.  *****************************************************************************/
  133.  
  134.  
  135. QD3D_EXPORT TQ3ObjectType Q3Camera_GetType(
  136.     TQ3CameraObject                camera);
  137.  
  138. QD3D_EXPORT TQ3Status Q3Camera_SetData(
  139.     TQ3CameraObject                camera,
  140.     const TQ3CameraData            *cameraData);
  141.  
  142. QD3D_EXPORT TQ3Status Q3Camera_GetData(
  143.     TQ3CameraObject                camera,
  144.     TQ3CameraData                *cameraData);
  145.     
  146. QD3D_EXPORT TQ3Status Q3Camera_SetPlacement(
  147.     TQ3CameraObject                camera,
  148.     const TQ3CameraPlacement    *placement);
  149.     
  150. QD3D_EXPORT TQ3Status Q3Camera_GetPlacement(
  151.     TQ3CameraObject                camera,
  152.     TQ3CameraPlacement            *placement);
  153.     
  154. QD3D_EXPORT TQ3Status Q3Camera_SetRange(
  155.     TQ3CameraObject                camera,
  156.     const TQ3CameraRange        *range);
  157.  
  158. QD3D_EXPORT TQ3Status Q3Camera_GetRange(
  159.     TQ3CameraObject                camera,
  160.     TQ3CameraRange                *range);
  161.  
  162. QD3D_EXPORT TQ3Status Q3Camera_SetViewPort(
  163.     TQ3CameraObject                camera,
  164.     const TQ3CameraViewPort        *viewPort);
  165.  
  166. QD3D_EXPORT TQ3Status Q3Camera_GetViewPort(
  167.     TQ3CameraObject                camera,
  168.     TQ3CameraViewPort            *viewPort);
  169.  
  170. QD3D_EXPORT TQ3Status Q3Camera_GetWorldToView( 
  171.     TQ3CameraObject                camera,
  172.     TQ3Matrix4x4                *worldToView);
  173.  
  174. QD3D_EXPORT TQ3Status Q3Camera_GetWorldToFrustum( 
  175.     TQ3CameraObject                camera,
  176.     TQ3Matrix4x4                *worldToFrustum);
  177.  
  178. QD3D_EXPORT TQ3Status Q3Camera_GetViewToFrustum(
  179.     TQ3CameraObject                camera,
  180.     TQ3Matrix4x4                *viewToFrustum);
  181.  
  182.  
  183. /******************************************************************************
  184.  **                                                                             **
  185.  **                            Specific Camera Routines                          **
  186.  **                                                                             **
  187.  *****************************************************************************/
  188.  
  189. /******************************************************************************
  190.  **                                                                             **
  191.  **                            Orthographic Camera                                  **
  192.  **                                                                             **
  193.  *****************************************************************************/
  194.  
  195. QD3D_EXPORT TQ3CameraObject Q3OrthographicCamera_New(
  196.     const TQ3OrthographicCameraData    *orthographicData);
  197.  
  198. QD3D_EXPORT TQ3Status Q3OrthographicCamera_GetData(
  199.     TQ3CameraObject                    camera,
  200.     TQ3OrthographicCameraData        *cameraData);
  201.  
  202. QD3D_EXPORT TQ3Status Q3OrthographicCamera_SetData(
  203.     TQ3CameraObject                    camera,
  204.     const TQ3OrthographicCameraData    *cameraData);
  205.  
  206. QD3D_EXPORT TQ3Status Q3OrthographicCamera_SetLeft(
  207.     TQ3CameraObject                    camera,
  208.     float                            left);
  209.     
  210. QD3D_EXPORT TQ3Status Q3OrthographicCamera_GetLeft(
  211.     TQ3CameraObject                    camera,
  212.     float                            *left);
  213.  
  214. QD3D_EXPORT TQ3Status Q3OrthographicCamera_SetTop(
  215.     TQ3CameraObject                    camera,
  216.     float                            top);
  217.     
  218. QD3D_EXPORT TQ3Status Q3OrthographicCamera_GetTop(
  219.     TQ3CameraObject                    camera,
  220.     float                            *top);
  221.  
  222. QD3D_EXPORT TQ3Status Q3OrthographicCamera_SetRight(
  223.     TQ3CameraObject                    camera,
  224.     float                            right);
  225.     
  226. QD3D_EXPORT TQ3Status Q3OrthographicCamera_GetRight(
  227.     TQ3CameraObject                    camera,
  228.     float                            *right);
  229.  
  230. QD3D_EXPORT TQ3Status Q3OrthographicCamera_SetBottom(
  231.     TQ3CameraObject                    camera,
  232.     float                            bottom);
  233.     
  234. QD3D_EXPORT TQ3Status Q3OrthographicCamera_GetBottom(
  235.     TQ3CameraObject                    camera,
  236.     float                            *bottom);
  237.  
  238.  
  239. /******************************************************************************
  240.  **                                                                             **
  241.  **                            ViewPlane Camera                                  **
  242.  **                                                                             **
  243.  *****************************************************************************/
  244.  
  245. QD3D_EXPORT TQ3CameraObject Q3ViewPlaneCamera_New(
  246.     const TQ3ViewPlaneCameraData    *cameraData);
  247.     
  248. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_GetData(
  249.     TQ3CameraObject                    camera,
  250.     TQ3ViewPlaneCameraData            *cameraData);
  251.  
  252. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_SetData(
  253.     TQ3CameraObject                    camera,
  254.     const TQ3ViewPlaneCameraData    *cameraData);
  255.  
  256. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_SetViewPlane(
  257.     TQ3CameraObject                    camera,
  258.     float                            viewPlane);
  259.     
  260. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_GetViewPlane(
  261.     TQ3CameraObject                    camera,
  262.     float                            *viewPlane);
  263.  
  264. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_SetHalfWidth(
  265.     TQ3CameraObject                    camera,
  266.     float                            halfWidthAtViewPlane);
  267.  
  268. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_GetHalfWidth(
  269.     TQ3CameraObject                    camera,
  270.     float                            *halfWidthAtViewPlane);
  271.  
  272. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_SetHalfHeight(
  273.     TQ3CameraObject                    camera,
  274.     float                            halfHeightAtViewPlane);
  275.  
  276. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_GetHalfHeight(
  277.     TQ3CameraObject                    camera,
  278.     float                            *halfHeightAtViewPlane);
  279.     
  280. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_SetCenterX(
  281.     TQ3CameraObject                    camera,
  282.     float                            centerXOnViewPlane);
  283.     
  284. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_GetCenterX(
  285.     TQ3CameraObject                    camera,
  286.     float                            *centerXOnViewPlane);
  287.     
  288. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_SetCenterY(
  289.     TQ3CameraObject                    camera,
  290.     float                            centerYOnViewPlane);
  291.     
  292. QD3D_EXPORT TQ3Status Q3ViewPlaneCamera_GetCenterY(
  293.     TQ3CameraObject                    camera,
  294.     float                            *centerYOnViewPlane);
  295.  
  296.  
  297. /******************************************************************************
  298.  **                                                                             **
  299.  **                            View Angle Aspect Camera                          **
  300.  **                                                                             **
  301.  *****************************************************************************/
  302.  
  303. QD3D_EXPORT TQ3CameraObject Q3ViewAngleAspectCamera_New(
  304.     const TQ3ViewAngleAspectCameraData    *cameraData);
  305.  
  306. QD3D_EXPORT TQ3Status Q3ViewAngleAspectCamera_SetData(
  307.     TQ3CameraObject                        camera,
  308.     const TQ3ViewAngleAspectCameraData    *cameraData);
  309.     
  310. QD3D_EXPORT TQ3Status Q3ViewAngleAspectCamera_GetData(
  311.     TQ3CameraObject                        camera,
  312.     TQ3ViewAngleAspectCameraData        *cameraData);
  313.  
  314. QD3D_EXPORT TQ3Status Q3ViewAngleAspectCamera_SetFOV(
  315.     TQ3CameraObject                        camera,
  316.     float                                fov);
  317.  
  318. QD3D_EXPORT TQ3Status Q3ViewAngleAspectCamera_GetFOV(
  319.     TQ3CameraObject                        camera,
  320.     float                                *fov);
  321.  
  322. QD3D_EXPORT TQ3Status Q3ViewAngleAspectCamera_SetAspectRatio(
  323.     TQ3CameraObject                        camera,
  324.     float                                aspectRatioXToY);
  325.     
  326. QD3D_EXPORT TQ3Status Q3ViewAngleAspectCamera_GetAspectRatio(
  327.     TQ3CameraObject                        camera,
  328.     float                                *aspectRatioXToY);
  329.  
  330.  
  331. #ifdef __cplusplus
  332. }
  333. #endif    /* __cplusplus */
  334.  
  335. #endif  /*  QD3DCamera_h  */
  336.